---
title: NextUI to HeroUI
description: Learn how to migrate your NextUI project to HeroUI, including automatic and manual migration steps.
---

# NextUI to HeroUI

HeroUI is the new identity for NextUI, bringing the same powerful components and features you love under a new name. This guide will help you migrate your existing NextUI project to HeroUI.

---

<CarbonAd/>

## Automatic Migration (Recommended)

The easiest way to migrate your NextUI project to HeroUI is using our official codemod:

<Steps>

### Run Migration

Execute the codemod in your project directory:

<PackageManagers
  commands={{
    npm: "npx @heroui/codemod@latest migrate",
    pnpm: "pnpm dlx @heroui/codemod@latest migrate",
    yarn: "yarn dlx @heroui/codemod@latest migrate",
    bun: "bunx --bun @heroui/codemod@latest migrate"
  }}
/>


> **Note:** If you're using a monorepo, run the codemod from the root directory

This will automatically:
- Update all package names from `@nextui-org/*` to `@heroui/*`
- Rename component imports and references
- Update TailwindCSS configuration
- Transform provider components
- Adjust any NextUI-specific utilities or hooks
- Update `.npmrc` file pnpm only

### Install Dependencies

After running the codemod, install the new dependencies:

<PackageManagers
  commands={{
    npm: "npm install",
    yarn: "yarn install",
    pnpm: "pnpm install",
    bun: "bun install"
  }}
/>

</Steps>

## Manual Migration

If you prefer to migrate manually, follow these steps:

<Steps>

### Update Dependencies

Replace NextUI packages with their HeroUI equivalents:

<PackageManagers
  commands={{
    npm: "npm uninstall @nextui-org/react && npm install @heroui/react",
    yarn: "yarn remove @nextui-org/react && yarn add @heroui/react",
    pnpm: "pnpm remove @nextui-org/react && pnpm add @heroui/react",
    bun: "bun remove @nextui-org/react && bun add @heroui/react"
  }}
/>

### Update TailwindCSS Configuration

Update your `tailwind.config.js`:

```js
// Before
const {nextui} = require("@nextui-org/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./node_modules/@nextui-org/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  plugins: [nextui()]
};

// After
const {heroui} = require("@heroui/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  plugins: [heroui()]
};
```

### Update Provider Component

Replace the NextUI provider with HeroUI's provider:

```jsx
// Before
import {NextUIProvider} from "@nextui-org/react";

// After
import {HeroUIProvider} from "@heroui/react";
```

### Update Imports

Update all component imports to use the new package name:

```jsx
// Before
import {Button, Input} from "@nextui-org/react";

// After
import {Button, Input} from "@heroui/react";
```

### Individual Packages

If you're using individual packages, update each package name:

```jsx
// Before
import {Button} from "@nextui-org/button";
import {Input} from "@nextui-org/input";
import {nextui} from "@nextui-org/theme";
import {NextUIProvider} from "@nextui-org/react";

// After
import {Button} from "@heroui/button";
import {Input} from "@heroui/input";
import {heroui} from "@heroui/theme";
import {HeroUIProvider} from "@heroui/react";
```

### Npmrc Pnpm Only

If you are using pnpm, you need to update your .npmrc file to use the new package name:

```bash
# Before
public-hoist-pattern[]=*@nextui-org/*

# After
public-hoist-pattern[]=*@heroui/*
```

</Steps>

## Verification

After migration, verify that:
1. All components render correctly
2. Theme customizations are preserved
3. No NextUI imports remain in your codebase
4. Your application builds without errors

<Blockquote color="primary">
  The functionality and API of all components remain the same - only the package names and imports have changed.
</Blockquote>

## Troubleshooting

If you encounter issues during migration, try these steps:

### NPM Users
If you're using `npm`, you may need to:
1. Delete your `node_modules` folder
2. Delete your `package-lock.json` file
3. Reinstall all packages with `npm install`

### Package.json Check
Ensure that no `@nextui-org` packages remain in your `package.json` dependencies or devDependencies.

### Need Help?
Join our Discord community in the **#nextui-to-heroui** channel [https://discord.gg/9b6yyZKmH4](https://discord.gg/9b6yyZKmH4) - our team is happy to help!

---

If you encounter any issues during migration, please [open an issue](https://github.com/heroui-inc/heroui/issues) on our GitHub repository.
